home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 1998 November / IRIX 6.5.2 Base Documentation November 1998.img / usr / share / catman / p_man / cat3 / Xm / XmGetPixmap.z / XmGetPixmap
Text File  |  1998-10-30  |  17KB  |  265 lines
  1.  
  2.  
  3.  
  4.      XXXXmmmmGGGGeeeettttPPPPiiiixxxxmmmmaaaapppp((((3333XXXX))))           UUUUNNNNIIIIXXXX SSSSyyyysssstttteeeemmmm VVVV           XXXXmmmmGGGGeeeettttPPPPiiiixxxxmmmmaaaapppp((((3333XXXX))))
  5.  
  6.  
  7.  
  8.      NNNNAAAAMMMMEEEE
  9.           XXXXmmmmGGGGeeeettttPPPPiiiixxxxmmmmaaaapppp - A pixmap caching function that generates a
  10.           pixmap, stores it in a pixmap cache, and returns the pixmap
  11.  
  12.      SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  13.           #include <Xm/Xm.h>
  14.           PPPPiiiixxxxmmmmaaaapppp XXXXmmmmGGGGeeeettttPPPPiiiixxxxmmmmaaaapppp(
  15.           SSSSccccrrrreeeeeeeennnn ****ssssccccrrrreeeeeeeennnn,
  16.           cccchhhhaaaarrrr ****iiiimmmmaaaaggggeeee____nnnnaaaammmmeeee,
  17.           PPPPiiiixxxxeeeellll ffffoooorrrreeeeggggrrrroooouuuunnnndddd,
  18.           PPPPiiiixxxxeeeellll bbbbaaaacccckkkkggggrrrroooouuuunnnndddd);
  19.  
  20.      VVVVEEEERRRRSSSSIIIIOOOONNNN
  21.           This page documents Motif 2.1.
  22.  
  23.      DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  24.           XXXXmmmmGGGGeeeettttPPPPiiiixxxxmmmmaaaappppuses the parameter data to perform a lookup in
  25.           the pixmap cache to see if a pixmap has already been
  26.           generated that matches the data. If one is found, a
  27.           reference count is incremented and the pixmap is returned.
  28.           Applications should use XXXXmmmmDDDDeeeessssttttrrrrooooyyyyPPPPiiiixxxxmmmmaaaappppwhen the pixmap is no
  29.           longer needed.
  30.  
  31.           _s_c_r_e_e_n    Specifies the display screen on which the pixmap
  32.                     is to be drawn.  The depth of the pixmap is the
  33.                     default depth for this screen.
  34.  
  35.           _i_m_a_g_e__n_a_m_e
  36.                     Specifies the name of the image to be used to
  37.                     generate the pixmap
  38.  
  39.           _f_o_r_e_g_r_o_u_n_d
  40.                     Combines the image with the _f_o_r_e_g_r_o_u_n_d color to
  41.                     create the pixmap if the image referenced is a
  42.                     bit-per-pixel image
  43.  
  44.           _b_a_c_k_g_r_o_u_n_d
  45.                     Combines the image with the _b_a_c_k_g_r_o_u_n_d color to
  46.                     create the pixmap if the image referenced is a
  47.                     bit-per-pixel image
  48.  
  49.           If a pixmap is not found, _i_m_a_g_e__n_a_m_e is used to perform a
  50.           lookup in the image cache. If an image is found, it is used
  51.           to generate the pixmap, which is then cached and returned.
  52.  
  53.           If an image is not found, the _i_m_a_g_e__n_a_m_e is used as a
  54.           filename, and a search is made for an XXXX11110000 or XXXX11111111 bitmap
  55.           file. If it is found, the file is read, converted into an
  56.           image, and cached in the image cache. The image is then used
  57.           to generate a pixmap, which is cached and returned.
  58.  
  59.           If _i_m_a_g_e__n_a_m_e has a leading slash (////), it specifies a full
  60.  
  61.  
  62.  
  63.      Page 1                                         (printed 10/24/98)
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70.      XXXXmmmmGGGGeeeettttPPPPiiiixxxxmmmmaaaapppp((((3333XXXX))))           UUUUNNNNIIIIXXXX SSSSyyyysssstttteeeemmmm VVVV           XXXXmmmmGGGGeeeettttPPPPiiiixxxxmmmmaaaapppp((((3333XXXX))))
  71.  
  72.  
  73.  
  74.           pathname, and XXXXmmmmGGGGeeeettttPPPPiiiixxxxmmmmaaaapppp opens the file as specified.
  75.           Otherwise, _i_m_a_g_e__n_a_m_e specifies a filename.  In this case,
  76.           XXXXmmmmGGGGeeeettttPPPPiiiixxxxmmmmaaaapppp looks for the file along a search path specified
  77.           by the XXXXBBBBMMMMLLLLAAAANNNNGGGGPPPPAAAATTTTHHHH environment variable or by a default
  78.           search path, which varies depending on whether or not the
  79.           XXXXAAAAPPPPPPPPLLLLRRRREEEESSSSDDDDIIIIRRRR environment variable is set.  The default search
  80.           path contains a lot of directories.  Therefore, XXXXmmmmGGGGeeeettttPPPPiiiixxxxmmmmaaaapppp
  81.           will need a relatively long time to search through all these
  82.           directories for pixmaps and bitmaps. Applications that use a
  83.           lot of pixmaps and bitmaps will probably run more quickly if
  84.           XXXXBBBBMMMMLLLLAAAANNNNGGGGPPPPAAAATTTTHHHH is set to a short list of directories.  In
  85.           addition to X bitmap files (XBM), Motif also supports XPM (X
  86.           Pixmap) file formats. The XXXXBBBBMMMMLLLLAAAANNNNGGGGPPPPAAAATTTTHHHH specifies the path for
  87.           both XBM and XPM files. Refer to the XXXXmmmmGGGGeeeettttPPPPiiiixxxxmmmmaaaappppBBBByyyyDDDDeeeepppptttthhhh
  88.           reference page for further details.
  89.  
  90.           The XXXXBBBBMMMMLLLLAAAANNNNGGGGPPPPAAAATTTTHHHH environment variable specifies a search path
  91.           for X bitmap files.  It can contain the substitution field
  92.           %%%%BBBB, where the _i_m_a_g_e__n_a_m_eargument to XXXXmmmmGGGGeeeettttPPPPiiiixxxxmmmmaaaapppp is
  93.           substituted for %%%%BBBB.  It can also contain the substitution
  94.           fields accepted by XXXXttttRRRReeeessssoooollllvvvveeeePPPPaaaatttthhhhnnnnaaaammmmeeee.  The substitution
  95.           field %%%%TTTT is always mapped to _b_i_t_m_a_p_s, and %%%%SSSS is always
  96.           mapped to NULL.
  97.  
  98.           If XXXXBBBBMMMMLLLLAAAANNNNGGGGPPPPAAAATTTTHHHH is not set but the environment variable
  99.           XXXXAAAAPPPPPPPPLLLLRRRREEEESSSSDDDDIIIIRRRR is set, the following pathnames are searched:
  100.  
  101.              +o  %%%%BBBB
  102.  
  103.              +o  $$$$XXXXAAAAPPPPPPPPLLLLRRRREEEESSSSDDDDIIIIRRRR////%%%%LLLL////bbbbiiiittttmmmmaaaappppssss////%%%%NNNN////%%%%BBBB
  104.  
  105.              +o  $$$$XXXXAAAAPPPPPPPPLLLLRRRREEEESSSSDDDDIIIIRRRR////%%%%llll____%%%%tttt////bbbbiiiittttmmmmaaaappppssss////%%%%NNNN////%%%%BBBB
  106.  
  107.              +o  $$$$XXXXAAAAPPPPPPPPLLLLRRRREEEESSSSDDDDIIIIRRRR////%%%%llll////bbbbiiiittttmmmmaaaappppssss////%%%%NNNN////%%%%BBBB
  108.  
  109.              +o  $$$$XXXXAAAAPPPPPPPPLLLLRRRREEEESSSSDDDDIIIIRRRR////bbbbiiiittttmmmmaaaappppssss////%%%%NNNN////%%%%BBBB
  110.  
  111.              +o  $$$$XXXXAAAAPPPPPPPPLLLLRRRREEEESSSSDDDDIIIIRRRR////%%%%LLLL////bbbbiiiittttmmmmaaaappppssss////%%%%BBBB
  112.  
  113.              +o  $$$$XXXXAAAAPPPPPPPPLLLLRRRREEEESSSSDDDDIIIIRRRR////%%%%llll____%%%%tttt////bbbbiiiittttmmmmaaaappppssss////%%%%BBBB
  114.  
  115.              +o  $$$$XXXXAAAAPPPPPPPPLLLLRRRREEEESSSSDDDDIIIIRRRR////%%%%llll////bbbbiiiittttmmmmaaaappppssss////%%%%BBBB
  116.  
  117.              +o  $$$$XXXXAAAAPPPPPPPPLLLLRRRREEEESSSSDDDDIIIIRRRR////bbbbiiiittttmmmmaaaappppssss////%%%%BBBB
  118.  
  119.              +o  $$$$HHHHOOOOMMMMEEEE////bbbbiiiittttmmmmaaaappppssss////%%%%BBBB
  120.  
  121.              +o  $$$$HHHHOOOOMMMMEEEE////%%%%BBBB
  122.  
  123.              +o  ////uuuussssrrrr////lllliiiibbbb////XXXX11111111////%%%%LLLL////bbbbiiiittttmmmmaaaappppssss////%%%%NNNN////%%%%BBBB
  124.  
  125.              +o  ////uuuussssrrrr////lllliiiibbbb////XXXX11111111////%%%%llll____%%%%tttt////bbbbiiiittttmmmmaaaappppssss////%%%%NNNN////%%%%BBBB
  126.  
  127.  
  128.  
  129.      Page 2                                         (printed 10/24/98)
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136.      XXXXmmmmGGGGeeeettttPPPPiiiixxxxmmmmaaaapppp((((3333XXXX))))           UUUUNNNNIIIIXXXX SSSSyyyysssstttteeeemmmm VVVV           XXXXmmmmGGGGeeeettttPPPPiiiixxxxmmmmaaaapppp((((3333XXXX))))
  137.  
  138.  
  139.  
  140.              +o  ////uuuussssrrrr////lllliiiibbbb////XXXX11111111////%%%%llll////bbbbiiiittttmmmmaaaappppssss////%%%%NNNN////%%%%BBBB
  141.  
  142.              +o  ////uuuussssrrrr////lllliiiibbbb////XXXX11111111////bbbbiiiittttmmmmaaaappppssss////%%%%NNNN////%%%%BBBB
  143.  
  144.              +o  ////uuuussssrrrr////lllliiiibbbb////XXXX11111111////%%%%LLLL////bbbbiiiittttmmmmaaaappppssss////%%%%BBBB
  145.  
  146.              +o  ////uuuussssrrrr////lllliiiibbbb////XXXX11111111////%%%%llll____%%%%tttt////bbbbiiiittttmmmmaaaappppssss////%%%%BBBB
  147.  
  148.              +o  ////uuuussssrrrr////lllliiiibbbb////XXXX11111111////%%%%llll////bbbbiiiittttmmmmaaaappppssss////%%%%BBBB
  149.  
  150.              +o  ////uuuussssrrrr////lllliiiibbbb////XXXX11111111////bbbbiiiittttmmmmaaaappppssss////%%%%BBBB
  151.  
  152.              +o  ////uuuussssrrrr////iiiinnnncccclllluuuuddddeeee////XXXX11111111////bbbbiiiittttmmmmaaaappppssss////%%%%BBBB
  153.  
  154.           If neither XXXXBBBBMMMMLLLLAAAANNNNGGGGPPPPAAAATTTTHHHH nor XXXXAAAAPPPPPPPPLLLLRRRREEEESSSSDDDDIIIIRRRR is set, the following
  155.           pathnames are searched:
  156.  
  157.              +o  %%%%BBBB
  158.  
  159.              +o  $$$$HHHHOOOOMMMMEEEE////%%%%LLLL////bbbbiiiittttmmmmaaaappppssss////%%%%NNNN////%%%%BBBB
  160.  
  161.              +o  $$$$HHHHOOOOMMMMEEEE////%%%%llll____%%%%tttt////bbbbiiiittttmmmmaaaappppssss////%%%%NNNN////%%%%BBBB
  162.  
  163.              +o  $$$$HHHHOOOOMMMMEEEE////%%%%llll////bbbbiiiittttmmmmaaaappppssss////%%%%NNNN////%%%%BBBB
  164.  
  165.              +o  $$$$HHHHOOOOMMMMEEEE////bbbbiiiittttmmmmaaaappppssss////%%%%NNNN////%%%%BBBB
  166.  
  167.              +o  $$$$HHHHOOOOMMMMEEEE////%%%%LLLL////bbbbiiiittttmmmmaaaappppssss////%%%%BBBB
  168.  
  169.              +o  $$$$HHHHOOOOMMMMEEEE////%%%%llll____%%%%tttt////bbbbiiiittttmmmmaaaappppssss////%%%%BBBB
  170.  
  171.              +o  $$$$HHHHOOOOMMMMEEEE////%%%%llll////bbbbiiiittttmmmmaaaappppssss////%%%%BBBB
  172.  
  173.              +o  $$$$HHHHOOOOMMMMEEEE////bbbbiiiittttmmmmaaaappppssss////%%%%BBBB
  174.  
  175.              +o  $$$$HHHHOOOOMMMMEEEE////%%%%BBBB
  176.  
  177.              +o  ////uuuussssrrrr////lllliiiibbbb////XXXX11111111////%%%%LLLL////bbbbiiiittttmmmmaaaappppssss////%%%%NNNN////%%%%BBBB
  178.  
  179.              +o  ////uuuussssrrrr////lllliiiibbbb////XXXX11111111////%%%%llll____%%%%tttt////bbbbiiiittttmmmmaaaappppssss////%%%%NNNN////%%%%BBBB
  180.  
  181.              +o  ////uuuussssrrrr////lllliiiibbbb////XXXX11111111////%%%%llll////bbbbiiiittttmmmmaaaappppssss////%%%%NNNN////%%%%BBBB
  182.  
  183.              +o  ////uuuussssrrrr////lllliiiibbbb////XXXX11111111////bbbbiiiittttmmmmaaaappppssss////%%%%NNNN////%%%%BBBB
  184.  
  185.              +o  ////uuuussssrrrr////lllliiiibbbb////XXXX11111111////%%%%LLLL////bbbbiiiittttmmmmaaaappppssss////%%%%BBBB
  186.  
  187.              +o  ////uuuussssrrrr////lllliiiibbbb////XXXX11111111////%%%%llll____%%%%tttt////bbbbiiiittttmmmmaaaappppssss////%%%%BBBB
  188.  
  189.              +o  ////uuuussssrrrr////lllliiiibbbb////XXXX11111111////%%%%llll////bbbbiiiittttmmmmaaaappppssss////%%%%BBBB
  190.  
  191.              +o  ////uuuussssrrrr////lllliiiibbbb////XXXX11111111////bbbbiiiittttmmmmaaaappppssss////%%%%BBBB
  192.  
  193.  
  194.  
  195.      Page 3                                         (printed 10/24/98)
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202.      XXXXmmmmGGGGeeeettttPPPPiiiixxxxmmmmaaaapppp((((3333XXXX))))           UUUUNNNNIIIIXXXX SSSSyyyysssstttteeeemmmm VVVV           XXXXmmmmGGGGeeeettttPPPPiiiixxxxmmmmaaaapppp((((3333XXXX))))
  203.  
  204.  
  205.  
  206.              +o  ////uuuussssrrrr////iiiinnnncccclllluuuuddddeeee////XXXX11111111////bbbbiiiittttmmmmaaaappppssss////%%%%BBBB
  207.  
  208.           These paths are defaults that vendors may change.  For
  209.           example, a vendor may use different directories for
  210.           ////uuuussssrrrr////lllliiiibbbb////XXXX11111111 and ////uuuussssrrrr////iiiinnnncccclllluuuuddddeeee////XXXX11111111.
  211.  
  212.           The following substitutions are used in these paths:
  213.  
  214.           %%%%BBBB        The image name, from the _i_m_a_g_e__n_a_m_e argument
  215.  
  216.           %%%%NNNN        The class name of the application
  217.  
  218.           %%%%LLLL        The display's language string.  This string is
  219.                     influenced by XXXXttttSSSSeeeettttLLLLaaaannnngggguuuuaaaaggggeeeePPPPrrrroooocccc.  The default
  220.                     string is determined by calling setlocale(_L_C__A_L_L,
  221.                     _N_U_L_L).
  222.  
  223.           %%%%llll____%%%%tttt     The language and territory component of the
  224.                     display's language string
  225.  
  226.           %%%%llll        The language component of the display's language
  227.                     string
  228.  
  229.           The contents of the file must conform to the rules for X11
  230.           bitmap files. In other words, Motif can read any X11
  231.           conformant bitmap file.
  232.  
  233.      RRRREEEETTTTUUUURRRRNNNN
  234.           Returns a pixmap when successful; returns
  235.           XXXXmmmmUUUUNNNNSSSSPPPPEEEECCCCIIIIFFFFIIIIEEEEDDDD____PPPPIIIIXXXXMMMMAAAAPPPPif the image corresponding to _i_m_a_g_e__n_a_m_e
  236.           cannot be found.
  237.  
  238.      RRRREEEELLLLAAAATTTTEEEEDDDD
  239.           XXXXmmmmDDDDeeeessssttttrrrrooooyyyyPPPPiiiixxxxmmmmaaaapppp(3), XXXXmmmmGGGGeeeettttPPPPiiiixxxxmmmmaaaappppBBBByyyyDDDDeeeepppptttthhhh(3),
  240.           XXXXmmmmIIIInnnnssssttttaaaallllllllIIIImmmmaaaaggggeeee(3), and XXXXmmmmUUUUnnnniiiinnnnssssttttaaaallllllllIIIImmmmaaaaggggeeee(3).
  241.  
  242.  
  243.  
  244.  
  245.  
  246.  
  247.  
  248.  
  249.  
  250.  
  251.  
  252.  
  253.  
  254.  
  255.  
  256.  
  257.  
  258.  
  259.  
  260.  
  261.      Page 4                                         (printed 10/24/98)
  262.  
  263.  
  264.  
  265.